---
title: Gemini CLI
description: Learn how to use the Gemini CLI community provider to access Google's Gemini models through the official CLI/SDK.
---

# Gemini CLI Provider

The [ai-sdk-provider-gemini-cli](https://github.com/ben-vargas/ai-sdk-provider-gemini-cli) community provider enables using Google's Gemini models through the [@google/gemini-cli-core](https://www.npmjs.com/package/@google/gemini-cli-core) library and Google Cloud Code endpoints. While it works with both Gemini Code Assist (GCA) licenses and API key authentication, it's particularly useful for developers who want to use their existing GCA subscription rather than paid use API keys.

## Version Compatibility

The Gemini CLI provider supports both AI SDK v4 and v5-beta:

| Provider Version | AI SDK Version | Status | Branch                                                                                 |
| ---------------- | -------------- | ------ | -------------------------------------------------------------------------------------- |
| 0.x              | v4             | Stable | [`ai-sdk-v4`](https://github.com/ben-vargas/ai-sdk-provider-gemini-cli/tree/ai-sdk-v4) |
| 1.x-beta         | v5-beta        | Beta   | [`main`](https://github.com/ben-vargas/ai-sdk-provider-gemini-cli/tree/main)           |

## Setup

The Gemini CLI provider is available in the `ai-sdk-provider-gemini-cli` module. Install the version that matches your AI SDK version:

### For AI SDK v5-beta (latest)

<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
  <Tab>
    <Snippet text="pnpm add ai-sdk-provider-gemini-cli ai" dark />
  </Tab>
  <Tab>
    <Snippet text="npm install ai-sdk-provider-gemini-cli ai" dark />
  </Tab>
  <Tab>
    <Snippet text="yarn add ai-sdk-provider-gemini-cli ai" dark />
  </Tab>

  <Tab>
    <Snippet text="bun add ai-sdk-provider-gemini-cli ai" dark />
  </Tab>
</Tabs>

### For AI SDK v4 (stable)

<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
  <Tab>
    <Snippet text="pnpm add ai-sdk-provider-gemini-cli@^0 ai@^4" dark />
  </Tab>
  <Tab>
    <Snippet text="npm install ai-sdk-provider-gemini-cli@^0 ai@^4" dark />
  </Tab>
  <Tab>
    <Snippet text="yarn add ai-sdk-provider-gemini-cli@^0 ai@^4" dark />
  </Tab>

  <Tab>
    <Snippet text="bun add ai-sdk-provider-gemini-cli@^0 ai@^4" dark />
  </Tab>
</Tabs>

## Provider Instance

You can import `createGeminiProvider` from `ai-sdk-provider-gemini-cli` and create a provider instance with your settings:

```ts
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';

// OAuth authentication (recommended)
const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});

// API key authentication
const gemini = createGeminiProvider({
  authType: 'api-key',
  apiKey: process.env.GEMINI_API_KEY,
});
```

You can use the following settings to customize the Gemini CLI provider instance:

- **authType** _'oauth-personal' | 'api-key' | 'gemini-api-key'_

  Required. The authentication method to use.

  - `'oauth-personal'`: Uses existing Gemini CLI credentials from `~/.gemini/oauth_creds.json`
  - `'api-key'`: Standard AI SDK API key authentication (recommended)
  - `'gemini-api-key'`: Gemini-specific API key authentication (identical to `'api-key'`)

  Note: `'api-key'` and `'gemini-api-key'` are functionally identical. We recommend using `'api-key'` for consistency with AI SDK standards, but both options map to the same Gemini authentication method internally.

- **apiKey** _string_

  Required when using API key authentication. Your Gemini API key from [Google AI Studio](https://aistudio.google.com/apikey).

## Language Models

You can create models that call Gemini through the CLI using the provider instance.
The first argument is the model ID:

```ts
const model = gemini('gemini-2.5-pro');
```

Gemini CLI supports the following models:

- **gemini-2.5-pro**: Most capable model for complex tasks (64K output tokens)
- **gemini-2.5-flash**: Faster model for simpler tasks (64K output tokens)

### Example: Generate Text

You can use Gemini CLI language models to generate text with the `generateText` function:

```ts
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';
import { generateText } from 'ai';

const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});

// AI SDK v4
const { text } = await generateText({
  model: gemini('gemini-2.5-pro'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

// AI SDK v5-beta
const result = await generateText({
  model: gemini('gemini-2.5-pro'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});
console.log(result.content[0].text);
```

Gemini CLI language models can also be used in the `streamText`, `generateObject`, and `streamObject` functions
(see [AI SDK Core](/docs/ai-sdk-core) for more information).

<Note>
  The response format differs between AI SDK v4 and v5-beta. In v4, text is
  accessed directly via `result.text`. In v5-beta, it's accessed via
  `result.content[0].text`. Make sure to use the appropriate format for your AI
  SDK version.
</Note>

### Model Capabilities

| Model              | Image Input         | Object Generation   | Tool Usage          | Tool Streaming      |
| ------------------ | ------------------- | ------------------- | ------------------- | ------------------- |
| `gemini-2.5-pro`   | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |
| `gemini-2.5-flash` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |

<Note>
  Images must be provided as base64-encoded data. Image URLs are not supported
  due to the Google Cloud Code endpoint requirements.
</Note>

## Authentication

The Gemini CLI provider supports two authentication methods:

### OAuth Authentication (Recommended)

First, install and authenticate the Gemini CLI globally:

```bash
npm install -g @google/gemini-cli
gemini  # Follow the interactive authentication setup
```

Then use OAuth authentication in your code:

```ts
const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});
```

This uses your existing Gemini CLI credentials from `~/.gemini/oauth_creds.json`.

### API Key Authentication

1. Generate an API key from [Google AI Studio](https://aistudio.google.com/apikey).

2. Set it as an environment variable in your terminal:

   ```bash
   export GEMINI_API_KEY="YOUR_API_KEY"
   ```

   Replace `YOUR_API_KEY` with your generated key.

3. Use API key authentication in your code:

```ts
const gemini = createGeminiProvider({
  authType: 'api-key',
  apiKey: process.env.GEMINI_API_KEY,
});
```

<Note>
  The Gemini API provides a free tier with 100 requests per day using Gemini 2.5
  Pro. You can upgrade to a paid plan for higher rate limits on the [API key
  page](https://aistudio.google.com/apikey).
</Note>

## Features

### Structured Object Generation

Generate structured data using Zod schemas:

```ts
import { generateObject } from 'ai';
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';
import { z } from 'zod';

const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});

const result = await generateObject({
  model: gemini('gemini-2.5-pro'),
  schema: z.object({
    name: z.string().describe('Product name'),
    price: z.number().describe('Price in USD'),
    features: z.array(z.string()).describe('Key features'),
  }),
  prompt: 'Generate a laptop product listing',
});

console.log(result.object);
```

### Streaming Responses

Stream text for real-time output:

```ts
import { streamText } from 'ai';
import { createGeminiProvider } from 'ai-sdk-provider-gemini-cli';

const gemini = createGeminiProvider({
  authType: 'oauth-personal',
});

const result = await streamText({
  model: gemini('gemini-2.5-pro'),
  prompt: 'Write a story about a robot learning to paint',
});

// Both v4 and v5 use the same streaming API
for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}
```

For more examples and features, including tool usage and multimodal input, see the [provider documentation](https://github.com/ben-vargas/ai-sdk-provider-gemini-cli).

## Model Parameters

You can configure model behavior with standard AI SDK parameters:

```ts
// AI SDK v4
const model = gemini('gemini-2.5-pro', {
  temperature: 0.7, // Controls randomness (0-2)
  maxTokens: 1000, // Maximum output tokens (defaults to 65536)
  topP: 0.95, // Nucleus sampling threshold
});

// AI SDK v5-beta
const model = gemini('gemini-2.5-pro', {
  temperature: 0.7, // Controls randomness (0-2)
  maxOutputTokens: 1000, // Maximum output tokens (defaults to 65536)
  topP: 0.95, // Nucleus sampling threshold
});
```

<Note>
  In AI SDK v5-beta, the `maxTokens` parameter has been renamed to
  `maxOutputTokens`. Make sure to use the correct parameter name for your
  version.
</Note>

## Limitations

- Requires Node.js ≥ 18
- OAuth authentication requires the Gemini CLI to be installed globally
- Image URLs not supported (use base64-encoded images)
- Very strict character length constraints in schemas may be challenging
- Some AI SDK parameters not supported: `frequencyPenalty`, `presencePenalty`, `seed`
- Only function tools supported (no provider-defined tools)

## Requirements

- Node.js 18 or higher
- Gemini CLI installed globally for OAuth authentication (`npm install -g @google/gemini-cli`)
- Valid Google account or Gemini API key
